═══ 1. Overview ═══ TarFront simplifies the process of backing up several files and directories in several root directories and tar volumes and restoring files from existing backups. It is a frontend for "tar" and "tape" which must be installed separately according to their documentation (look for gtar*.zip and gtak*.zip). A little understanding of "tar" and "tape" on the side of the user would be helpful, even if not necessarily needed. Currently, TarFront does not compare or verify files from archives. This is planned for a later version. This release of TarFront is public domain. You're free to do anything with it, as long as no files are modified or left out of the archive. The author does not guarantee that anything will work as documented here (most things should, though ). You have been warned. For comments write to ekraemer@pluto.camelot.de. Later versions (3.x) will become shareware with moderate pricing in the range of 40-50 US$; versions 2.x (bug fixes, minor improvements) will always remain free, though. See also:  Installation  Startup  Usage  Examples  Common Problems ═══ 2. Installation ═══ To install TarFront, unpack the TarFront archive and either use install.cmd, or copy all files into a directory of your choice. If using install.cmd, you have to specify a target directory, which must be different from the temporary directory you unpacked the archive into. Also, the language has to be specified. install c:\tarfront20 e Copies all files to c:\tarfront20\ and installs the english version of the program. install c:\tarfront20 d Copies all files to c:\tarfront20\ and installs the german version of the program. All program/dialog texts are german; there's no german online help, though. install.cmd will create a folder on your desktop; this folder contains a link to the executable and documentation and a template for INI files. You can start TarFront by double-clicking copies of this template. ═══ 3. Startup ═══ TarFront needs one startup parameter, which is a INI file name. This INI file will take up all options of the current session. It is suggested that there's one INI file for every tape (in the case of permanent data backups) or one INI file for every type of regular backup (i.e., monthly, weekly, daily, with different settings for the "generations", and so on). Tape directory files, which contain the directories of the archives, should be named like their INI files plus an additional extension to permit easy retrival of files. If you used "install" to install TarFront, you can simply drag *.TFN files onto the executable or double-click on *.TFN files to start TarFront. ═══ 4. Usage ═══  Tree  Main Menu  Main Toolbar  Restoring ═══ 4.1. The Tree ═══ TarFront manages its target files and direcories in a tree. There are three types of items in this tree: Files and directories These are passed directly to tar; directories always contain themselves, all files contained in them and all subdirectories. These entries can be modified by a check mark, which is the default and means that this item will be included, and a cross, which means that this item will be excluded. To toggle between those, double-click on the item. Note: If you want to exclude some files from others, put the exclude entries after the include entries.. Root directories Root directories can (and should) have child directories and/or files. Before processing these, the current directory is set to the root directory and all other files/directories are stripped to relative paths. Example: suppose you want to backup a directory inside another temporary directory. Because it would be stupid to have the temporary directory on the tape as well, you can declare the temporary directory as root directory and put the "real" backup directory into it. The combination of a root directory "e:\temp" and a directory "e:\temp\back" inside it would lead to the tar command "tar [options] -C e:\temp back", which means that tar changes to the directory/drive "e:\temp" and backups the file or directory "back". Volumes Volume entries start a new tape volume. Each volume is processed as a single tar process and contains all entries that lie "inside" the volume. The default volume name, when none is given, is an (almost) unique number. Specifying the to-be-backed-up files and directories is simple - just drag them out of any WPS folder into the main window. You may also add them via the menu, but then you have to enter their names. To change entries, hold the Alt key and left-click on them (like you're used to from the WPS). Be aware, though, that TarFront does not check any item for validity - if you enter any wrong values, you have to live with the result. To remove entries, drag them onto your Shredder WPS object. To associate directories/files with root directories, drag them onto the latter. The same is true for volumes - drag all things that make up a volume into it. Defaults Volume and root entries are not mandatory. There may be only one single entry (a file or directory), which will be backed up with absolute path into a unnamed volume. On the other hand it is more convenient to have volume entries every time and there could a lot of volumes and root directories in one single tree. "Rooted" entries can arbitrarily be mixed with "non-rooted" ones. See also:  Main Menu  Main Toolbar  Restoring ═══ 4.2. The Menu ═══ The TarFront menu contains the following items: Options The following options are available: Tar settings You can adjust all settings for "tar" that have an effect on backups. For more information, refer to the tar documentation, "tar --help" or this chapter. Font The font which is used for trees, containers and the status display can be set with this option. Exit Exits the program. Items Every type of tree entry can be added here. To change the names to meaningful values (i.e., paths/files), hold the Alt key and left-click on the name. Be sure to use only absolute path names; TarFront does not validate anything, so take special care that your files or directories are spelled correctly (there will be no damage resulting from wrong values, but not everything you wanted to backup will be processed). You may also delete the selected item through this menu, although you can always drag items onto the WPS Shredder object. Tape This menu contains all "tape" commands that need no further user interaction. All commands that may damage things are disabled by default; click on "Enable all" to enable them. This setting is not saved in the INI file for savety. For more information on "tape", refer to GTAK.INF, shipped with GTAK. Help This menu permits access to the online help facility. See also:  Tree  Main Toolbar  Restoring ═══ 4.3. The Main Toolbar ═══ The main toolbar menu contains the following items: With this button you can start the backup process. Everything in the tree will be backed up; a separate tar process is started for every volume (one after the other). Be careful not to terminate TarFront when a backup is still in progress - the tar process will not be killed, and you may get very strange results. TarFront will open a tree-like display containing all files available for restoring. See also:  Tree  Main Menu  Restoring ═══ 4.4. Restoring ═══ The restore window, which is brought up through a button in the main toolbar, displays the tape directory file which was created when backups were created. By double-clicking on any item, you can tag it - together with any subitems in the case of directories or volumes - for restore. Note: The special volume name *** is used to contain all files and directories that were not backed up using a real one. This does not happen with backups created with TarFront, since this program always adds a volume name. Be careful when selecting directories that may contain enhanced attributes, like the desktop folders. It doesn't suffice to enable all subdirectories or -files, you must enable the directory itself (and maybe disable other directories or files that you don't want to restore). Otherwise, the EAs of the directory will not be restored. When finished tagging items, click this toolbar button to start restoring files. You will be asked to confirm your selection. See also:  Tree  Main Menu  Main Toolbar ═══ Tape Directory Progress ═══ TarFront is reading the tape directory file. Depending on the size of the file and the available memory, this may take a (long, long) while. See also:  Restoring ═══ Confirm Restore ═══ Please confirm that TarFront should restore the marked files from tape. It will display the volume name, the total count of files and the total size (in bytes). Note: Slightly more space will be needed due to Enhanced Attributes and directory structures. You should specify a target directory; if you do not do so, all files will be written to the current directory (which is pretty much random). See also:  Restoring ═══ 5. Tar Options ═══ This notebook contains all options pertaining to tar itself. For an explanation of their meaning (if not obvious), look at "tar --help", the tar man/GNU-info pages, or one of the following chapters:  General  Display  Tape Dir  Generation  Misc  Commands ═══ 5.1. General ═══ Archive EAs (-p) Save Extended Attributes on tape. This should be enabled, especially when backing up WPS folders (\Desktop). Archive everything (-pp) Save all information about files on the tape, including three different time stamps. Note: You may not be able to restore such an archive on non-OS/2 systems. Use buffer (-Q) Use an intermediate buffer between tar and the tape device, which can speed up backups, while using a lot of RAM. Note: If the tape directory file is not written (or size 0), then try to disable this function. Note: -D cannot be used together with -Q if the tape device is a file, and no streamer. POSIX format (--posix) Use a more modern format, preserving long file names. As opposed to the standard format, there will be no name mangling for long names. Verify archive (-W) This function cannot be used on tape devices, and is thus disabled. Ask for confirmation (-w) Ask the user before acutally doing anything (i.e., ask for each file being backed up). Compress (--zip) Filther the archive through the specified compression program. If none is given, gzip is used. If you want to append options to the compression program, use "program,options". Tape device (-f) Enter the tape device (e.g., SCSI:+LB,TAPE$3) or a filename (e.g., c:/archive.tar) here. The default is the value from the environment variable TAPE. Note: -D cannot be used together with -Q if the tape device is a file, and no streamer. Only files newer than (-N) Only store files newer than the date given. ═══ 5.2. Display ═══ Display directory progress (-E) Displays each directory as it is processed. Display file progress (-v) Displays each file as it is processed and may thus slow down the backup overly. Display record number (-R) Shows the record number with each message. Display total bytes (--totals) Prints how many bytes have been written. ═══ 5.3. Tape Dir ═══ Use tape directory file (-D) Enables the use of a tape directory file. It contains detailed information about all the files in an archive, together with the position of the file on the tape. It is much easier (and faster) to restore a file which is known through a tape directory, because the tape can fast-forward to the file, instead of having to search through the whole tape. Note: -D cannot be used together with -Q if the tape device is a file, and no streamer. Directory file Enter the name of the directory file here. It is advised that there be one file for each tape. Successive backups will append to this file. Addressing If you are sure that your streamer supports it, use absolute and relative addressing (which is faster/better), otherwise use relative only. The latter requieres volume labels, so you have to use volume labels in the backup tree. ═══ 5.4. Generation ═══ Use generation management (--gen=...) This option enables the generation management. There are three types of generations: First Every file will be backed up and the archive flags re-set. Second Every file with a set archive flag will be backed up; the archive flag is not re-set. First Every file will be backed up and every archive flag re-set. GNU style (-g) When enabled, tar will keep information about each file in a separate data base (entered in the entry field), and will use this information instead of the archive flag. Here is some information out of the GNU Tar documentation regarding incremental backups:  Incremental Backups Based on OS/2's "Archive" Bit  GNU Incremental Backups  Notes on Both Variants ═══ 5.4.1. Incremental Backups Based on OS/2's "Archive" Bit ═══ This is a straight quote from the GTAR documentation shipped with GTAK. It is only here to explain the generation management - you don't need to enter these commands directly. --generation=first First (full) backup. The archive bit is reset after each file is processed. --generation=second Incremental backup. Only files with the archive bit set are archived. The archive bit is not reset, so each increment is based on the last full backup. To restore using s increments, you need the full backup and the last incremental backup. Intermediate increments are not required. --generation=incremental Incremental backup. Only files with the archive bit set are archived. The archive bit is reset after each file is processed, so each incremental backup is based on the last incremental backup. To restore using i increments, you need the full backup and each incremental backup in the order they were run. If TAR is interrupted in i incremental backups, you should no longer run incremental backups. The next backup should be a full backup, since TAR resets the archive bits after each file is processed. When restoring archive bit based incremental backups, files which were deleted since the last full backup are nevertheless restored to disk. You do not have to specify --generation on restore. Examples tar -cE --abs --gen=f --label=Full-7.7.1994 c:/ d:/ e:/ tar -cE --abs --gen=i --label=Incr-15.8.1994 c:/ d:/ e:/ tar -xv c:/os2 ═══ 5.4.2. GNU Incremental Backups ═══ This is a straight quote from the GTAR documentation shipped with GTAK. It is only here to explain the generation management - you don't need to enter these commands directly. --incremental=dumpfile --generation=first First (full) backup. The dumpfile is erased before use. --incremental=dumpfile --generation=second Incremental backup. Files are only archived if the "modified" timestamp exceeds the timestamp mentioned in the dumpfile or if its directory is not mentioned in the dumpfile. The dumpfile is not updated, so each increment is based on the last full backup using the same dumpfile. To restore using s increments, you need the full backup and the last increment. Intermediate increments are not required. You do not need the dumpfile. --incremental=dumpfile --generation=incremental Incremental backup. Files are only archived if the "modified" timestamp exceeds the timestamp mentioned in the dumpfile or if its directory is not mentioned in the dumpfile. The dumpfile is updated after all files are processed, so each increment is based on the last incremental backup using the same dumpfile. To restore using i increments, you need the full backup and each incremental backup in the order they were run. You do not need the dumpfile. If TAR is aborted, the dumpfile it not updated, so the repeated run will start at the same point as the aborted run. When using GNU incremental backups, archived directories contain info about all files located in this directory. When restoring with --incremental, all files which exist in the directory on disk but not in the directory on the archive, are removed from the disk, since they are left over from previous incremental restores. Note that for syntactic reason, you have to pass some filename as argument to --incremental even though the file itself is neither required nor touched on restore. If you do not specify --incremental on restore, creation and accessed timestamps are not extracted by default. You do not have to specify --generation on restore. Since OS/2 does not maintain directory timestamps the way UNIX does, the OS/2 version processes all directories in the way mentioned in the previous paragraphs, not just the ones which were changed in some way since the last update of the dumpfile. So the directories can take up a considerably amount of space in each incremental backup even if not a single file has to be archived, and most likely it causes a lot of stop-and-go when using a QIC type device. GNU incremental backups implicitly define --all-timestamps and --all-files. GNU incremental backup archives are incompatible to standard TAR archives. You might not be able to read such archives with standard TAR programs. Examples tar -cE --abs --incr=date-1.dat --gen=f --label=Full-7.7.199 4 c:/ d:/ e:/ tar -cE --abs --incr-date-1.dat --gen=i --label=Incr-15.8.19 94 c:/ d:/ e:/ tar -xv --incr=nul c:/os2 ═══ 5.4.3. Notes on Both Variants ═══ OS/2 does neither update the "modified" timestamp not does it cause the "archive" bit to be set, when only the extended attribute part of a file or directory have been changed. So incremental backups unavoidably fail to archive files where only extended attributes have been changed. However, directory records are created for all processed directories independent of timestamps or archive bits, so extended attributes of directories are always archived (with -p, of course). To include the complete state of the OS/2 desktop even in incremental backups, run TAR non-incremental on critical directories before, creating a disk file with tar cpf c:/desktop.tar "c:/OS!2 2.0 Desktop" (or whatever name your desktop tree has), and include this disk file in the tape backup. Note that there are a few other important extended attributes such as printer settings. ═══ 5.5. Misc ═══ Ignore blocks of zero (-i) Ignores blocks of zeros in archives (which are normally EOF, end of file). Multi-Volume support (-M) Continue on another tape if tape is full. V7 format (-o) Write an older format, used for compatibility. Convert to FAT (--fat) Convert filenames to FAT 8.3 format. Block size (-b) Enter the block-size (x512 Bytes). Note: The same block size must be used when restoring. Archive ACLs (--acl) Archive OS/2 ACL (access control list) entries for each file, which are used to keep the permissions of files on networked file systems. Note: If you get the message Out of memory when starting tar with this option, disable it. Tape length (-L) Change tapes after writing the given length. Run script after tape (-F) Run the given script after each tape. This option implies Multi-Volume support. Begin at file (-K) Begin the backup with the given file. Read full blocks (-B) Reblock when reading. ═══ 5.6. Commands ═══ Additional Options Everything which is entered here will be appended to the tar command string. It will be inserted between the last TarFront option and before the first file name. Complete TAR Command Here, all options that are passed on to tar (except file names) are displayed. ═══ 6. Examples ═══  Backing up with root and volume  Restoring a directory ═══ 6.1. Backing up with root and volume ═══ 1. Drag the directory which should be backed up into the empty TarFront window: 2. Now, the directory is displayed active in the tree: 3. Since we only want to backup the contents of the chosen directory, not caring about the path, we create a root directory by dragging the same directory again (out of the WPS folder into the TarFront window) and toggling it with double-clicks of the left mouse button until it looks like this: 4. Finally, we can move the directory item into the root directory by dragging it: 5. As a last step, we create the volume name by selecting Items/Add/Volume from the menu and naming the new entry by clicking the left mouse button on it while holding the Alt key. We also move the root directory into the volume by dragging it. Then we click the "Backup" icon: ═══ 6.2. Restoring a directory ═══ Restoring a Subdirectory This example shows how to restore one subdirectory from a volume. By double-clicking the QEDIT entry, the directory and all contained items are selected. Parent directories are displayed half selected and half normal since they contain both selected and deselected items. ═══ 7. Common Problems ═══ Q: When restoring, I get a lot of messages like tar: Seek to physical block 511 tar: Seek error on SCSI:+LB,TAPE$3, physical block 511+1573: Invalid seek. A: Turn off buffering ("Use buffer" on the "General" page). If that doesn't help, make sure you entered the correct tape device on the "General" page or - if you didn't activate this option - in the TAPE environment variable. See the GTAK documentation for hints on this setting. Q: The tape directory file is not written or has no size. A: Turn off buffering. Q: I'm archiving to a tar file while using a tape directory file (-D) and buffering (-Q). It doesn't work. A: Turn off buffering. Q: I get the message "out of memory" when running a backup and tar aborts. A: Turn off the saving of ACLs since most probably you're machine has none, anyway ("Archive ACLs" on the "Misc" page). Q: When backing up, tar slows down and seems to completely stand still after some time. A: The status window gets crowded, which slows down OS/2. Don't let tar display each single file when backing up large volumes. Display directories instead ("Display" page). ═══ 8. History ═══ 2.1  Fixed: all known bugs (almost)  Improved: documentation  Improved: WPS folder  Improved: scanning of removable drives disabled  Added: support for virtually all versions of TAR tape directories.  This is no longer a BETA program. 2.0b  Fixed: all known bugs  Improved: tar settings notebook  Improved: documentation  Improved: error recovery  Added: german language (program only)  Added: restore  Added: toolbars  Added: integrated tar/tape output  Added: misc. features (fonts, insert drive items, "complete command", ...) 1.0b  First release  Backup only